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MADMAC Version 1*07 release notes, January, 1990. 

Using .cargs used to cause subsequent global symbols to disappear from 
the symbol table. Now it doesn’t. 

A movem instruction with no register list (i.e. ’’movem.l (sp)+,”) 
assembled without error; it now reports ’’missing regsiter list.” 


MADMAC Version 1.05 release notes, August, 1988. 

This version of MadMac replaces version 1.00 and fixes some small bugs: 

Symbols beginning with a capital L were not included in the 
object file output. They should have been (and now are) excluded only 
in AS68 compatibility mode, to avoid cluttering the output with 
compiler-generated symbols. 

Forward branches declared ”short” (such as bra.s, dbra.s, bsr.s) 
but whose targets were too far away did not cause an assembly-time 
error; incorrect machine code was silently generated. They now cause 
assembly-time errors. 

Symbols appeared in the object file symbol table in the order 
they were referenced in the source, not the order they were declared. 

Now the order more nearly matches the order of declaration (but not 
perfectly). 

The disp(An,Xn.s) addressing mode produced correct machine code, 
but incorrect output in the listing file. Now the output is correct. 
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Introduction 


Introduction 

This document describes MADMAC, a fast macro assembler for the (58000. MAD- 
MAC currently runs on the Atari ST and under 1.2 BSD VAX UNIX. It was written 
at Atari Corporation by programmers who needed a high performance assembler 
for their work. 

MADMAC.’ is intended to be used by programmers who write mostly in as¬ 
sembly language. It was not originally a back-end to a (’ compiler, therefore it 
lias creature comforts that are usually neglected in such back-end assemblers. It 
supports include lib's, macros, symbols with limited scope, some limited control 
structures, and other feature's. MADMAC’ is also blindingly fast, another feature 
often sadly and obviously missing in today’s assemblers . 1 

MADMAC is not entirely compatible with the AS (>8 assembler provided with 
t he original Atari ST Developer's Kit, but most change's are minor and a few minutes 
with an editor should allow you to assemble your current source' file's. If you are' an 
AS(58 use'r, before you leap into the unknown please read the sectiou on Notes for 
AS68 Users. 

This manual was typese't with Tj.]X and the' Computer Modern fonts, and it 
was printed on the Atari SLM-801 laser printer with a MKCiA ST. Kxcopt for 200 
lines of assembly language', the* assembler is written eutirely in C. 


1 It processes* 30,000 line's a minute' on a lightly le>aded VAX 11/780; maybe* 
10,000 on a -V20-ST with an SII-201 hard disk. Net it could be* spe'd up e've'ii more* 
with some* e'llort and without n'sorting to asse'inbly language*; C doesn't have to be* 
slow! 
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Introduction 


Got ting Started 

=> Write protect your distribution disk and make a backup of it now. Put the 
original disk in a safe place. 

o The distribution disk contains a file calk'd README that you should read. 
This file contains important news about the contents of the distribution disk 
and summarizes the most recent changes to the tools. 

o Hard disk users can simply copy the executable files to their work or binary 
directories. People with floppy disks can copy the executables to ramdisks, 
install the assembler with the -q option, or even work right off of the floppies. 

o You will need an editor that can produce "normal" format text files. Micro 
Kmacs will work well, as will most other commercial program editors, but not 
most word processors (such as First Word or Microsoft Write). 

o You will probably want, to examine or get a listing of the file "ATARI.S". It 
contains lots of definitions for the Atari ST', including BIOS variables, most 
BIOS, XBIOS and (JKM DOS traps, and line-A equates. We (or you) could 
split the file up into pieces (a file for line-A equates, a file for hardware and 
BIOS variables and so on), but M A DM AC is so fast that it doesn't matter 
much. 

o Read the rest of the manual, especially the first two chapters on Tlic Com¬ 
mand Line* and Using MADMAC. The distribution disk contains example 
programs that you can look at, assemble and modify. 
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The Command Line 


The assembler is called "mac.prg." The command line takes the form: 

mac [switches] [files ... ] 

A command line consists of any number of switches followed by the names of files 
to assemble. A switch is specified with a dash (-) followed immediately by a key 
character. Key characters are not case-sensitive, so “-<1" is the same as "-D". Some 
switches accept (or require) arguments to immediately follow the key character, 
with no spaces in between. 

Switch order is important. Command lines are processed from left to right in 
one pass, and switches usually take effect when they are encountered. In general it 
is best to specify all switches before the name's of any input file's. 

If the command line is entirely empty them MADMAC prints a copyright mes¬ 
sage' and enters an "interactive" mode, prompting for successive command linens 
with a star (*). An empty command line will exit (See the examples in the chapter 
on Using MADMAC). After each assembly in interactive mode, the assembler 
will print a summary of the amount of memory used, the amount of memory left, 
the number of linos processed, and the number of seconds the assembly took. 

Input files are assumed to have the extension “.s”; if a filename has no extension 
(i.e. no dot) then “.s" will be appended to it. More than one source filename may be 
specified: the files are assembled into one object file, as if they were concatenated. 

MADMAC normally produces object code in "file.o" if "file.s" is the first 
input filename. If bthe first input file is a special character device, the output name 
is iioiiame.o. The -o switch (see below) can be used change the output file name. 


Switch 

Description 

-dname[= value] 

Deline symbol, with optional value. 

-e [file].err]] 

Direct error messages to the specified file. 

-fill 

Produce Mark Williams format object file. 

-fimi 

Like “-fill" , but move underscores to end of symbol names. 

-i path 

Set iiiclude-file directory search path. 

-1 [file], pm]] 

Construe! and direct assembly listing to the specified file. 

-ofilc[.o] 

Direct object code output to the specified file. 

-P 

Produce an executable (.prg) output file. 

-ps 

Produce an executable (.prg) output file with symbols. 

-q 

Make MADMAC 1 resilient in memory (Atari ST only). 

-s 

Warn about unoptiinized long branches. 

-11 

Assume that all undefined symbols are external. 

-V 

Verbose mode (print running dialogue). 

-yn 

Set listing page size to n lines. 

-6 

“Back end" mode for Aleyon (’<>£. 

filef.s] 

Assemble the specified file. 
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The switches are described below. A summary of all the switches is given in 
the table. 

-cl 

The -cl switch permits symbols to be defined on the' command line. The name 
of the symbol to be defined immediately follows the switch (no spaces). The 
symbol name may optionally be followed by an ecjuals sign ( = ) and a decimal 
number. If no value is specified the symbol's value is zero. The symbol at¬ 
tributes are “defined, not referenced, and absolute". This switch is most useful 
for enabling conditionally-assembled debugging code on the command line; for 
example: 

-dDEBUG -dLoopCount=999 -dDebugLevel=55 


-e 

The -c switch causes M ADM AC- to send error messages to a file, instead of the 
console. If a filename immediately follows the switch character, error messages 
are written to the specified file. If no filename is specified, a file is created with 
the default extension “•err" and with the root name taken from the first input 
file name (e.g. error messages are written to “file. err" if “file" or “file.s" is 
the first input file name). If no errors are encountered, then no error listing 
file is created. Beware! If an assembly produces no errors, any error file from 
a previous assembly is not removed. 

.fm 

-film 

The -fm and -film switches cause M A DM AO to generate Mark Williams style 
object files instead of Alcyon object files. These files may be linked with the 
Mark Williams linker. The -fniu switch causes underscores on the first char¬ 
acter of a global symbol name to be moved to the end of the name, as per the 
Mark Williams C compiler naming convention. That is, “_main" will become 
“main." and “_ main" will become “.main.". 

-i 

The -i switch allows automatic directory searching for include files. A list of 
semi-colon seperated directory search paths may be mentioned immediately 
following the switch (with no space's anywhere). For example: 

-im: ; c: include; c: include\sys 

will cause the assembler to search the current directory of device M. and the 
directories include and include\sys on drive C. If -i is not specified, and the 
enviroment variable “MACPATH" exists, its value is used in the same manner. 
For example, users of the Mark Williams shell could put the following line in 
their profile script to achieve the same result as the -i example above: 

setenv MACPATH="m:;c:include;c:include\sys" 


fhe -1 switch causes M ADM AC to generate an assembly listing file. If a file¬ 
name immediately follows the switch character, the listing is written to the 
specified file. If no filename is specified, then a listing file is created with the 
default extension “.pm" and with the root name taken from the first input file 
name (e.g. the listing is writ ten to “file. pm" if “file" or “file.s" is the first 
input file name). 


The -o switch causes M ADM AC to write object code on the specified file. No 
default extension is applied to the filename. For historical reasons the filename 
can also be seperated from the switch with a space (e.g. “-o u file"). 
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-P 

-ps 

The -p and -ps switches cause MADMAC to produce an Atari ST executable 
file with the default extension of “.prg”. If there are any external references 
at the end of the assembly, an error message is emitted and no executable tile 
is generated. The -p switch does not write symbols to the executable file. The 
-ps switch includes symbols (Aicyon format) in the executable file. 


-<1 

The -q switch is aimed primarily at users of floppy-disk-only systems. It causes 
MADMAC to install itself in memory, like a RAMdisk. Then the program 
m.prg (which is very short less than a sector) can be used instead of 
mac.j)rg, which can take ten or twelve seconds to load. 

-s 

The -s switch causes MADMAC 1 to generate a list of unoptimized forward 
branches as of warning messages. This is used to point out branches that could 
have been short (e.g. “bra” could be “bra.s”). 

-u 

The -u switch takes effect at the end of the assembly. It forces all referenced 
and undefined symbols to bo global, exactly as if they had been made global 
with a .extern or .globl directive. This can be used if you have a lot of 
external symbols, and you don't feel like declaring them all external. 

-v 

The -v switch turns on a “verbose” mode in which MADMAC prints out. (for 
example) the names of the files it is currently processing. Verbose mode is 
automatically entered when MADMAC* prompts for input with a star. 

-y 

The -y switch, followed immediately by a decimal number (with no intervening 
space), sets the number of lines in a page. MADMAC will produce N lines 
before emitting a form-feed. If N is missing or less than 10 an error message is 
generated. 

-G 

The -6 switch takes effect when it is mentioned. It allows MADMAC to be 
used as a back end to the Aicyon C compiler. 1 Note: the assembler will 
produce code that is typically ten percent larger and ten percent slower than 
the output of the Aicyon assembler, therefore use of this switch for production 
code is discouraged. 


1 The -6 switch is not a compatibility mode for AS(58 — it has been carefully 
tailored to accept the output of the Aicyon C compiler. 
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Lei 's assemble and link some example programs. These programs are included 
on the distribution disk in the "EXAMPLES'' directory — you should copy them to 
your work area before continuing. In the following examples we adopt the conven¬ 
tions that the shell prompt is a percent sign (ft) and that your input (the stuff you 
type) is presented in bold face. 

If you have been reading carefully, you know that MADMAC- can generate 
an executable file without linking. This is useful for making small, stand alone 
programs that don't require externals or library routines. For example, the following 
two commands: 

ft mac example.s 
ft alii -s exainple.o 

could be replaced by the single command: 

ft mac -ps example.s 

since you don't need the linker for stand-alone object file's. 

Successive source files named in the command line are are concatenated, as in 
this example, which assembles three files into a single executable, as if they were' 
one big file: 

ft mac -p bugs shift images 

Of course you can get the same effect by using the .include directive, but sometimes 
it is convenient to do the concatenation from the command line. 

Here we have an unbelievably complex command line: 

ft mac -lzorf -y95 -o tmp -eback -ini: -Ddcbug=123 -ps example 

This produces a listing on Hie file called "zorf .pm" with 95 lines per page, writes 
the executable code' (with symbols) to a file called “tmp.prg," writes an error list¬ 
ing to the file "hack.err," specifies an include-file path that includes the current 
directory on the drive "M:," defines the symbol "debug" to have the value 123, and 
assembles the file "example . s." ('Fake a deep breath you got all that?) 

One last thing. If there are any assembly errors, MADMAC? will terminate 
with an exit cotie of 1. If the assembly succeeds (no errors, although there may be 
warnings) the exit code will be 0. This is primarily for use with "make" utilities. 

Interactive Mode 

If you invoke MADMAC 1 with an empty command line it will print a copyright, 
message and prompt you for more commands with a star (*). This is useful if you 
are used to working directly from the desktop, or if you want to assemble several files 
in succession without having to reload the assembler from disk for each assembly. 

Jn interactive mode, the assembler is also in verbose' mode (just as if you had 
specified -v on each command line): 
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Usins MADMAC 
% mac 


MADMAC Atari Macro Assembler 
Copyright 1987 Atari Corporation 
Beta version 0.12 Jun 1987 lmd 


* -ps example 
[Including: example.s] 

[Including: atari.s] 

[Leaving: atari.s] 

[Leaving: example.s] 

[Writing executable file: example.prg] 

36K used, 3658K left, 850 lines, 2.0 seconds 

* 

You can see that the assembler gave a "blow-by-blow” account of the fib's it pro¬ 
cessed, as well as a summary of the assembly's memory usage, the number of lines 
processed (including macro and repeal-block expansion), and how long the assembly 
took. 

The assembler prompts for another command with the star. At this point you 
can either type a new command line for the assembler to process, or you can exit 
by typing control-C or an empty line. 

Tilings You Should Be Aware Of 

MADMAC' is a one pass assembler. This means that it gets all of its work done by 
reading each source file exactly once and then "back-patching” to fix up forward 
references. This one-pass nature is usually transparent to the programmer, with 
the following important exceptions: 

o Jo listings, the object code for forward references is not shown. Instead, lower- 
cast' "xx"s art' displayed for each undefined byte, as in the following example: 


60xx .1: 

bra.s 

.2 

; forward branch 

xxxxxxxx 

dc.l 

.2 

; forward reference 

60FE .2: 

bra.s 

.2 

; backward reference 


o Forward branches (including BSRs) are never optimized to their short forms. 
To g< *t a short forward branch it is necessary to explicitly use the ".s” suffix in 
tile sourer code. 

o Error m•-stages may appear at the end of the assembly, refering to earlier source 
linos that contained undefined symbols. 

o All obj ( i t <«>d« generated must fit in memory. Running out of memory is a 
fatal < re r ill it \ou must deal with by splitting up your source fib's, re-sizing 
or eliminating memory-using programs such as ramdisks and desk accessories, 
or bu\ mg more H A M . 

Forward Branches 

MADMAC ibx-N not optimize forward branches for you, hut it will tell you about 
them if you ns* tin -s (short branch) option: 

•/, mac -s example.s 

"example.s M , line 20: warning: unoptimized short branch 

With the -e option you can redirect the error output to a file, and determine by 
hand (or editor macros) which forward branches are safe to explicitly declare short. 
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Notes for AS68 Users 

M ADM AO is not entirely compatible with the Alcyon assembler, A SO 8. This section 
outlines the major differences. In practice, we have found that very few changes are 
necessary to make ASOS source code assemble. 

o A semicolon (;) must be used to introduce a comment, except that a star (*) 
may be used in the first column. ASG8 treated anything following the operand 
field, preceeded by whitespace, as a comment. (M A DM AO treats a star that 
is not in column 1 as a multiplication operator). 

o Labels require colons (even labels that begin in column 1). 

o Conditional assembly directives are called if, else and endif. ASt>8 called these 
ifuc, ifeq (etc.), and etude. 

o The tilde (~) character is an operator, and hack-quote ( ( ) is an illegal character. 
AS<>8 permit ted the tilde and hack-quote characters in symbols. 

o There are no equivalents to AS(58‘s org or section directives. AS(>8 s page 
directive has become eject. The AS<>8 .xdef and .xref directives are not imple¬ 
mented, but .globl makes these unnecessary anyway. The directives .comline, 
mask2, idnt and opt, which were nil ini piemen ted and ignored in AS<>8, are 
not legal in MADMAO. 

o The location counter cannot he manipulated with a st atement of the form: 

* = cxpn'ssiou 

o The ds directive is not permitted in the text or data segments (except in -6 
mode); an error message is issued. Use deb instead to reserve large' blocks of 
init ialized storage. 

o Hack-slashes in strings are “electric" characters that are used to escape (-like 
character codes. Watch out for G EM DOS path name's in ASCII constants - 
you will have to convert them to double-backslashes. 

Notes for Mark Williams C Users 

M ADM AC will generate object code' that the Mark Williams C linker. Id, will 
accept. This has been tested only with version 2.0 of the' Mark Williams package. 
Some notable difference's bet ween MADMAC and the Mark Williams assembler, as, 
are': 

o MWC permits lb-character symbol names in the object file, and MADMAC’ 
supports this; 

o MWC object filers can contain more code and data sections than the MADMAC.’ 
(Alcyon) object code format. MADMAC’ maps its code sections as follows: 


MWC ’ Space 

M A DM AC ’ Space 

sliri (shared instruction) 
prvi (private instruction) 
hssi (uninitialized instruction) 
slu'd (shared data) 
prvd (private data) 
bssd (uninitialized data) 
debug information 
symbols 
absolute 

text 

unsupported 

unsupported 

data 

unsupported 

bss 

unsupported 

symbols 

abs. equates, etc. 
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It is not possible for MADMAC to generate codr in t he Mark Williams private 
instruction, private data or uninit ialized instruct ion spaces. 

o None of the Mark Williams assembler directives (e.g. “.long" and “.odd") are 
.supported. None of t he MW(’ non-standard addressing modes an' supported. 

o The Mark Williams debugger, db, does not support the A Icyon-format symbols 
produced with the -ps switch: it complains about the format of the executable 
file and aborts. 

o MADMAC does not support the method by which the Mark Williams slit'll 
passes long command lines to programs. Command lines are truncated to 127 
characters. 

Using M ADM AC as a Back-End to tlio Aleyon C Compiler 

MADMAC can be used in place of the AS(>8 assembler as a back-end for the Aleyon 
version *1.14 C compiler. The “-C" switch t urns on a moth' that warps and perverts 
M ADM AC's ordinary syntax into accepting what the Aleyon compiler dishes out. 
This can be used in a hatch lile (for instance) with a line that looks like: 

mac -6 -o 7.1.o m:7,l 

(Assuming that device k ‘M:" is where the source was put by compiler phase cl68). 
You should be await' t hat ASb8 generally product's better and faster code than 
MADMAC, although it is slower to assemble. 

Text File Format 

For those using editors other than the “Emacs" style ones (Micro-Emacs, Mince, 
etc.) this section documents the source file format that MADMAC* expects. 

o Files must contain characters with ASCII values less than 128: it is not per- 
missable to have characters with their high bits set unless t hose characters are 
contained in strings (i.e. between single or double quotes) or in comments. 

o Lines of text are terminated with carriage-return/line-feed, linefeed alone, or 
carriage-ret urn alone. 

o The tile is assumed to end with the last terminated line. If there is text beyond 
the last line terminator (e.g. control-Z) it is ignored. 
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Statements 

A statement may contain up to four fields which are identified by order of ap¬ 
pearance and terminating characters. The general form of an assembler statement 

is: 

label: operator operand(s) ; comment 

The label and comment fields are optional. An operand field may not appear 
without an operator field. Operands are seperated with commas. Blank lines are 
legal. If the first character on a line is an asterisk (*) or semicolon (;) then the 
entire line is a comment. A semicolon anywhere on the line (except in a string) 
begins a comment field which extends to the end of the line. 

The label, if it appears, must be terminated with a single or double colon. If 
it is terminated with a double colon it is automatically declared global. It is illegal 
to declare a confined symbol global (see: Symbols and Scope). 

Equates 

A statement may also take one of these special forms: 

symbol equ expression 
symbol = expression 
symbol == expression 
symbol set expression 
symbol reg register list 

The first two forms are identical; they equate the symbol to the value of an 
expression, which must be defined (no forward references). The third form, double¬ 
equals (==), is just like an equate except that it also makes the symbol global. (As 
with labels, it is illegal to make a confined equate global.) The fourth form allows 
a symbol to be set to a value any number of times, like a variable. The last form 
equates the symbol to a 1 (5-bit register mask specified by a register list. It is possible 
to equate confined symbols (see: Symbols and Scope). For example: 


cr 

equ 

13 

; carriage-return 

If 

as 

10 

; line-feed 

DEBUG 

== 

1 

; global debug flag 

count 

set 

0 

; variable 

count 

set 

count + 1 

; increment variable 

.regs 

reg 

d3-d7/a3-a6 

; register list 

. cr 

— 

13 

; confined equate 

Symbols and 

Scope 




Symbols may start with an uppercase or lowercase letter (A-Z a-z), an underscore 
(_), a question mark (?) or a period (.). Each remaining character may be an 
upper or lowercase letter, a digit (0-9). an underscore, a dollar sign ($), or a ques¬ 
tion mark. (Periods can only begin a symbol, they cannot appear as a symbol 
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continuation character). Symbols are terminated with a character that is not. a 
symbol continuation character (e.g. a period or comma, whitespace, etc.). Case is 
significant for user-defined symbols, but not for GSOOO mnemonics, assembler direc¬ 
tives and register names. Symbols are limited to 100 characters. When symbols 
are written to the object file they are silently truncated to eight (or sixteen) char¬ 
acters (depending on the object file format) with no check for (or warnings about) 
collisions. 

For example', all of the following symbols are legal and unique: 

reallyLongSymbolName .reallyLongConfinedSymbolName 


alO 

ret 

move 

dc 

frog 

aa6 

a9 ???? 

.al 

.ret 

.move 

.dc 

• frog 

. a9 

Q ?*??? 

.0 

.00 

.000 

. 1 

.11 

.111 

. , _ 


_frog ?zippo? sys$system atari Atari ATARI aTaRi 

while all of the following symbols are illegal: 

12days dc.10 dc.z 'quote .right.here 

(Dwork hi. there $money$ "tilde 

Symbols beginning with a period (.) are confined: their scope is between two 
normal (unconfined) labels. Confined symbols may be labels or equates. It is illegal 
to make a confined symbol global (with the ".glob!” directive, a double colon, or a 
double equals). Only unconlined labels delimit a confined symbol's scope; equates 
(of any kind) do not count. For example, all symbols are unique and have unique 
values in the following: 


zero:: 

subq. v 

#l,dl 


bmi.s 

.ret 

.loop: 

clr. w 

(a0) + 


dbra 

dO,.loop 

.ret: 

rts 


FF:: 

subq. w 

#1 ,dl 


bmi. s 

.99 

.loop: 

move.v 

#-l,(a0)+ 


dbra 

dO,.loop 

.99: 

rts 



Confined symbols are useful since the programmer has to be much loss inventive 
about finding small, unique names that also have meaning. 

It is legal to define symbols that have the same names as processor mnemonics 
(such as "move” or "rts") or assembler directives (such as "‘.even”). Indeed, one 
should be careful to avoid typographical errors, such as this classic (in (5502 mode): 

.6502 

. org = $8000 

which equates a coufined symbol to a hexadecimal value, rather than setting the 
location counter, which the .org directive does (without the equals sign). 

Keywords 

The following names, in all combinations of uppercase and lowercase, are keywords 
and may not be used as symbols (e.g. labels, equates, or the names of macros): 

equ set reg 

sr ccr pc sp ssp usp 

dO dl d2 d3 d4 d5 d6 d7 

aO al a2 a3 a4 a5 a6 a7 

rO rl r2 r3 r4 r5 r6 r7 

r8 r9 rlO rll r!2 r!3 r!4 r!5 
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Constants 

Numbers may be decimal, hexadecimal, octal, binary or concatenated ASCII. The 
default radix is decimal, and it may not be changed. Decimal numbers are specified 
with a string of digits (0-9). Hexadecimal numbers are specified witl) a leading 
dollar sign ($) followed by a string of digits and uppercase or lowercase letters (A-F 
a-f). Octal numbers are specified with a leading at-sign ((D) followed by a string 
of octal digits (0-7). Binary numbers are specified with a leading percent sign 
(•/•) followed by a string of binary digits (0-1). Concatenated ASCII constants are 
specified by enclosing from one to four characters in single or double quotes. For 
example: 

1234 decimal 

$ 1234 hexadecimal 

<0777 octal 

>£10111 binary 

"z" ASCII 

'frog* ASCII 

Negative numbers are specified with a unary minus (-). For example: 

-5678 -0334 -$4e71 

-•/.U Oil —'z' - M WIHD" 


Strings 

Strings are contained between double (") or single (') quote marks. Strings may 
contain lion-printable characters by specifying “backslash" scapes, similar to the 
ones used in the C programming language. M A DM AC will generate a warning if a 
backslash is followed by a character not appearing below: 


w 

$5c 

backslash 

\n 

$0a 

line-feed (newline) 

\b 

$08 

backspace 

\t 

$09 

tab 

\r 

$0d 

carriage-return 

\f 

$0c 

fort n-feed 

\e 

$lb 

escape 

V 

$27 

single-fpioie 

V 

$22 

double-quote 


It is possible for strings (but not symbols) to contain characters with their high 
bits set (i.e. character codes 1*2 S . . .*255). 

You should be aware that backslash characters are popular in GEM DOS path 
names, and that you may have to escape backslash characters in your existing source 
code. For example, to get the file M c: \auto\ahdi. s" you would specify the string 
"c: WautoWahdi. s M . 


Register Lists 

Register lists are special forms used with the movom mnemonic and the .rog 
directive. They are l(5-bit values, with bits 0 through 15 corresponding to registers 
DO through A7. A register list consists of a series of register names or register 
ranges seperated by slashes. A register range consists of two register names, Rdj 
and R n, nt < a. seperated by a dash. For example: 
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register list value 


d0-d7/a0-a7 $FFFF 
d2-d7/a0/a3-a5 $39FC 
d0/dl/a0-a3/d7/a6-a7 $CF83 
dO $0001 
r0-rl5 $FFFF 


Register lists and register ec| nates may be used in conjunction with the mo vein 
mnemonic, as in this example: 


temps reg 
keeps reg 
allregs reg 

movem.1 
movem.l 
movem.1 
movem.1 


d0-d2/a0-a2 ; 
d3-d7/d3-a6 ; 
d0-d7/a0-a7 ; 
#temps,-(sp) ; 
d0-d2/a0-a2,-(sp) 
#keeps,-(sp) ; 
(sp)+,#keeps ; 


temp registers 
registers to preserve 
all registers 
these two lines ... 

; ... are identical 
save ’’keep" registers 
restore "keep" registers 
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Expressions 


All values are computed with 32-bit 2's complement arithmetic. For boolean op¬ 
erations (such as if or assort) zero is considered false, and non-zero is considered 
true. 

Expressions are evaluated strictly left-to-right, with no 
regard for operator precedence. 

Thus the expression "I -f 2 * 3" evaluates to 0, not 7. However, precedence may be 
forced with parenthesis (()) or square-brackets (□). 


Types 

Expressions belong to one of three classes: undefined, absolute or relocatable. An 
expression is undefined if it involves an undefined symbol (e.g. an undeclared sym¬ 
bol, or a forward reference). An expression is absolute if its value will not change 
when the program is relocated (for instance, the number 0, all labels declared in 
ail abs section, and all Atari ST hardware register locations are absolute values). 
An expression is relocatable if it involves exactly one symbol that is contained in a 
text, data or BSS section. 

Only absolute values may be used with operators other than addition ( + ) or 
subtraction (-). It is illegal, for instance, to multiply or divide by a relocatable or 
undefined value. Subtracting a relocatable value from another relocatable value in 
the same section results in an absolute value (the distance between them, positive 
or negative). Adding (or subtracting) an absolute value to or from a relocatable 
value yeilds a relocatable value (an offset from the relocatable address). 

It is iiii|K>rlant to realize that relocatable values belong to the sections they 
are defined in (e.g. text, data or BSS), and it is not permissible to mix and match 
sections. For example, in this code: 


linel: 

dc.l 

line2, linel+8 

line2: 

dc.l 

linel, line2-8 

line3: 

dc.l 

line2-linel, 8 

error: 

dc.l 

linel+line2, line2 » 1, line3/4 


Line 1 deposits two longwords that point to line 2. Line 2 deposits two longwords 
that point to line 1. Line 3 deposits two longwords that have the absolute value 
eight. The fourth line will result in an assembly error, since the expressions (re¬ 
spectively) attempt to add t wo relocatable values, shift a relocatable value right by 
one. and divide a relocatable value by four. 

The pseudo-symbol (star) has the value that the current section's location 
counter had at the beginning of the current source lino. For example, these two 
statements deposit three pointers to the label '‘bar": 

foo: dc.l *+4 

bar: dc.l *, * 

Similarly, the pseudo-symbol '$' has the value that the current section's loca¬ 
tion counter has, and it is kept up to date as the assembler deposits information 
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“across" a line of source code. For example, these two statements deposit four 
pointers to the label "zip": 

zip: dc.l $+8, $+4 

zop: dc.l $, $-4 

Unary Operators 


Operator 

Description 

f 

" "defined symbol 
""referenced symbol 
" ~ street stringLstring'2 
""inacdef macro Name 

Unary minus (2's complement ). 
Logical (boolean) NOT. 

Tilde: bitwise not (I s complement). 
True if symbol has a value. 

True if symbol has been referenced. 
True if the strings are equal. 

True if the macro is defined. 


o The boolean operators generate the value l if the expression is true, and 0 if 
it is not. 

o A symbol is referenced if it is involved in an expression. A symbol may have 
any combination of at tributes: undefined and unreferenced, defined and unref¬ 
erenced (i.e. declared but never used), undefined and referenced (in the case 
of a forward or external reference), or defined and referenced. 

Biliary Operators 


Operator 

Description 

+ - * / 

The usual arithmetic operators. 

7. 

Modulo. 

* 1 * 

Bit-wise AND, OR and Exclusive-OR. 

« » 

Bit-wise shift left and shift right. 

A 

A 

II 

V 

II 

V 

Boolean magnitude comparisons. 

= 

Boolean equality. 

<> * s 

Boolean inequality. 


o All binary operators have the same precedence: expressions are evaluated 
strictly left to right. 

o Division or modulo by zero yields an assembly error, 
o The “<>" and “! =" operators are synonyms. 

o Note that the modulo operator (%) is also used to introduce binary constants 
(see: Constants). A percent, sign should be followed by at least one space if 
it is meant to be a modulo operator, and is followed by a ‘O’ or T\ 

Special Forms 


Special Form 

Description 

date 
" "time 

The current system date (Ciemdos format). 
The current system time (Ciemdos format). 


o The “"date" special form expands to the current system date, in Ciemdos 
format. The format is a lb-bit word with bits 0.. .4 indicating the day of the 
month (1 .. .31), bits 5 . . .8 indicating the month (l ... 12), and bits 9 ... 15 
indicating the year since 1980, in the range 0 ... 119. 
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o The “"time” special form expands to the current system time, in (’Jemdos 
format. The format is a 1 (5-hit word with bits ()...'! indicating the current 
second divided by 2, bits 5... 10 indicating the current minute 0...59, and 
bits 11... 15 indicating the current hour 0 .. .23. 


Example Expressions 

line address contents source code 


1 00000000 4480 labl: 

2 00000002 427900000000 lab2: 

3 =00000064 equl 

4 =00000096 equ2 

5 00000008 00000064 

6 0000000C 7FFFFFE6 

7 00000010 0001 

8 00000012 0000 

9 00000014 00000002 

10 00000018 0001 

11 0000001A 0001 


neg.l 

dO 

clr .w 

labl 

= 

100 

= 

equl + 50 

dc.l 

labl + equl 

dc.l 

(equl + ~equ2) » 1 

dc. w 

""defined equl 

dc. w 

""referenced lab2 

dc.l 

lab2 

dc. w 

“"referenced lab2 

dc. v 

labl = (lab2 - 6) 


Lines 1 through four here are used to set up the rest of the example. Line 5 deposits 
a relocatable pointer to the location 100 bytes beyond the label "labl/' Line (> is 
a nonsensical expression that uses the ~ and right-shift operators. Line 7 deposits 
a word of 1 because the symbol "oqul" is defined (in line 3). 

Line 8 deposits a word of 0 because the symbol "lab2," defined in line 2, has 
not been referenced. But the expression in line 9 reference's the symbol "lab2," so 
line 10 (which is a copy of line 8 ) deposits a word of 1 . Finally, line 11 deposits a 
word of l because the boolean equality operator evaluates to true. 


The operators ""defined" and ""referenced" are particularly useful in 
conditional assembly. For instance, it is possible to automatically include debugging 
code if the debugging code is referenced, as in: 


lea 

string,aO 

; A0 -> message 

jsr 

debug 

; print a message 

rts 


; and return 

dc .b 

"Help me, Spock!",0 

; (the message) 


. iif ""defined debug, .include "debug.s" 

The jsr statement references the symbol debug. Near the end of the source file, the 
".iif' statement includes the file "dobug.s" if the symbol debug was referenced. 
In production code, presumably all references to the debug symbol will be removed, 
and the debug source file will not be included. (We could have as easily made the 
symbol debug external, instead of including another source file). 
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Directives 


Assembler directives may be any mix of upper- or lowerca.se. The leading periods 
are optional, though they are shown here and their use is encouraged. Directives 
may he proceeded by a label; the label is defined before the directive is executed. 
Some directives accept si/e suffixes (.b, .s, .w or .1); the default is word (.w) if no 
size is specified. The .s suffix is identical to .b. Directive's relating to the (>r>02 are 
described in the chapter on 6502 Support. 


.even 

If the location counter for the current section is odd, make it even by adding 
one to it. In text and data sections a zero byte is deposited if necessary. 

.assert expression [, expression ...] 

Assert that the conditions are true (non-zero). If any of the comma-seperated 
expressions evaluates to zero ail assembler warning is issued. For example: 

.assert ♦-start = $76 
.assert stacksize >= $400 

.bss 

.data 

.text 

Switch to the BSS. data or text segments. Instructions and data may not 
be assembled into the BSS segment, but symbols may be defined and storage 
may be reserved with the .ds directive. Each assembly starts out in the text- 
segment. 

.abs [location] 

Start an absolute section, beginning with the specified location (or zero, if 
no location is specified). An absolute section is much like BSS, except that 
locations declared with .ds are based absolute. This directive is useful for 
declaring structures or hardware locations. 

For example, t he following equates: 

VPLANES = 0 
VWRAP = 2 
C0NTRL = 4 
INTIN = 8 
PTSIN =12 

could be as easily defined as: 

.abs 

VPLANES: ds.w 1 
VWRAP: ds.w 1 

CONTRL: ds.l 1 

INTIN: ds.l 1 

PTSIN: ds.l 1 
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.comm symbol . expression 

Specifies a label ami the size of a common region. The label is made global, 
thus confined symbols cannot be made common. The linker groups all com¬ 
mon regions of the same name; the largest size determines the real size of the 
common region when the file is linked. 

.dcf.size] expression [.expression .. .] 

Deposit initialized storage in the current section. If the specified' size is word 
or long, the assembler will execute a .even before depositing data. If the size 
is .b, then strings that are not part of arithmetic expressions are deposited 
byte-by-byte. If no size is specified, the default is .w. This directive cannot be 
used in the BSS section. 

.doh[..s;ze] expression !. expression2 

(Generate an initialized block of expression'! bytes, words or longwords of the 
value expn'ssion'J . If the specified size is word or long, the assembler will 
execute .even before generating data. If no size is specified, the default is .w. 
This directive cannot be used in the BSS section. 

•ds[. size] expression 

Reserve space in the current segment for the appropriate number of bytes, 
words or longwords. If no size is specified, the default size is .w. If the size 
is word or long, the assembler will execute .even before reserving space. This 
directive can only be used in the BSS or ABS sections (in text or data, use 
.deb to reserve large chunks of initialized storage.) 

.init[.size] [^expression ,]e.\'prrssiofi[.size] [. ...] 

Generalized initialization directive. The size specified on the directive becomes 
the default size for the rest of the line. (The “default" default size is .w.) A 
comma-seperated list of expressions follows the directive; an expression may be 
followed by a size to override the default size. An expression may be proceeded 
by a sharp sign, an expression and a comma, which specifies a repeat count to 
be applied to the next expression. For example: 

.init.l -1, O.w, #16,'z’.b, #3,0, 11.b 

will dc*|K>sii a long word of -1, a word of zero, sixteen bytes of lower-case V, 
thr<s* lon^uonU of zero, and a byte of I I. 

No auto-alignment is performed within the line, but a .even is done once 
(befon tli< ♦ rsi value is deposited) if the default size is word or long. 

.cargs [tcspn^ion , }>vmboI[.size] [, symbol[.size]. ..] 

Compute m<i< k offsets to C (and other language) arguments. Each symbol is 
assigned an .dilute value (likccqu) which starts at expression and increases 
by the mz< of each symbol, for each symbol. If the expression is not supplied, 
the default starling value is 1. For example: 

.cargs #8, .fileName.1, .openMode, .bufPointer.1 

could be used to declare offsets from A6 to a pointer to a filename, a word 
containing an open mode, and a pointer to a buffer. (Note that, the symbols 
used here are confined). Another example, a ( -style *\string-length" function, 
could be written as: 
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_strlen:: .cargs .string 

move.l .string(sp),a0 
moveq #-l,dO 
.1: addq.l #l,dO 

tst.b (a0) + 
bne . 1 
rts 


; declare arg 
; aO -> string 
; initial size = -1 
; bump size 
; at end of string? 

; (no — try again) 

; return string length 


. 011(1 

End the assembly. In an include file, end the include fil<> and resume assembling 
the superior file. This statement, is not required, nor are warning messages 
generated if it is missing at the end of a file. This directive may be used inside 
conditional assembly, macros or .rept blocks. 


•if expression 

.else 

.endif 

Start a block of conditional assembly. If the expression is true (non-zero) then 
assemble the statements bet ween the .if and the matching .endif or .else. 
If the expression is false, ignore the statements unh'ss a matching .else is 
encountered. Conditional assembly may be nested to any depth. 

It is possible to exit a conditional assembly block early from within an include 
file (with end) or a macro (with endm). 


.iif expression , statement 

Immediate version of .if. If the expression is true (non-zero) then the state¬ 
ment, which may he an instruction, a directive or a macro, is executed. If 
the expression is false, the statement is ignored. No .endif is required. For 
example: 

.iif age < 21, canDrink = 0 

.iif weight > 500, dangerFlag = 1 

.iif !(~~defined DEBUG), .include dbsrc 


.macro name [ formal , formal , ... ] 

.endm 

.exitm 

Define a macro called name with the specified formal arguments. The macro 
definition is terminated with a .endm statement. A macro may be exited early 
with the .exitm directive. See the chapter on Macros for more information. 

.undefmac macroName [. macroName.. .] 

Remove the macro-definition for the specified macro names. If reference is 
made to a macro that is not defined, no error message is printed and the name 
is ignored. 

.rept expression 

.einlr 

The statements between the .rept and .endr directives will he repeated ex¬ 
pression times. If the expression is zero or negative, no statements will be 
assembled. No label may appear on a line containing either of these directives. 

.globl symbol [, symbol ...] 

.extern symbol [. symbol.. .] 

Each symbol is made global. None of the symbols may be confined symbols 
(those starting with a period). If the symbol is defined in the assembly, the 
symbol is exported in the object file. If the symbol is undefined at the end 
of the assembly, and it was referenced (i.e. used in an expression), then the 
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symbol value is imported as an external reference that must, be resolved by the 
linker. The .extern directive is merely a synonym for .globl. 

•include "file" 

Include a file. If the filename is not enclosed in (piot.es, then a default extension 
of “.s is applied to it. II the filename is quoted, t hen the name is not changed 
in any way. 

Note: If the filename is not a valid symbol, then the assembler will generate an 
error message. \ou should enclose filenames such as “atari.s" in quotes, 
because such names are not symbols. 

If the include file cannot bo found in the current directory, then the direc¬ 
tory search path, as specified by -i on the commaudliiie. or by the MACPATH 
enviroment st ring, is t raversed. 

.ejoot 

Issue a page eject in the list ing file. 

.title "string" 

.suhttl [-] "siring" 

Set the title or subtitle on the listing page. The title should be specified on 
the the first line or the source program in order to take effect, on the first page. 
The second and subsequent use's of .title! will cause page ejects. The second 
and subsequent uses of .silhttl will cause page ejects unless the subt it le string 
is preceeded by a el ash (-). 

.list 

.lilist 

Enable or disable source code listing. These directives increment and decrement 
an internal counter, so they may be appropriately nested. They have no effect 
if t he -1 switch is not specified oil the coiimiamlliue. 

.goto label 

This directive provides unstructured How of control within a macro definition. 
It will transfer control to the line of the macro containing the specified goto 
hi he I. A goto label is a symbol preceeded by a colon that appears in the first 
column of a source line within a macro definition: 

: hihei u 

where the label itself can be any valid symbol name, followed immediately by 
whitespace and a valid source line (or end of line). The colon must appear in 
the first column. 

The goto-label is removed from the source line prior to macro expansion 
to all intents and purposes the label is invisible except to the .goto directive. 
Macro expansion does not take place within the label. 

Kor example, hen 1 is a silly way to count from 1 to 10 without using .rc»pt: 

.macro Count 
count set 1 

:loop dc.w count 

count set count + 1 

iif count <= 10, goto loop 
. endm 
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Mnemonics 

All of the standard Motorola (>£000 mnemonics and addressing inodes are supported; 
you should refer to Tlie Motorola MG8000 Programmer's Reference Manual 
for a description of the instruction set and the allowable addressing modes for each 
instruction. With one major exception (forward branches) the assembler performs 
all the reasonable optimizations of instructions to their short or address register 
forms. 

Register nanu's may he in upper or lowercase. The alternate forms RO through 
R15 may be used to specify DO through A7. All register names are keywords, and 
may not be used as labels or symbols. None of the (58010 or (>8020 register names 
are keywords (but they may become keywords in the future). 

Addressing Modes 


Assembler Syntax 

Description 

Du 

Dat a register direct 

An 

Address register direct 

(An) 

Address register indirect 

(Ail) + 

Address register indirect post increment 

-(All) 

Address register indirect predecrement 

A/i) 

Address register indirect with displacement 

Ih lisp (kit, Xi [ .size] ) 

Address register indirect indexed 

abs.y 

Absolute short 

a/» 

Absolute (long or short) 

nhs. 1 

Forced absolute long 

disp (PC) 

Program counter with displacement 

hihsp(PC, Xi) 

Program counter indexed 

#//nm 

Immediate 


Branches 

Si net' MADM \< «» «>n« pass assembler, forward branches cannot be automatically 

optimized to ih«ir short lorm. Instead, unsized forward branches are assumed to 
be long. Rackw trd l>nin< h«*s are always optimized to the short form if possible. 

A table 11 *. * i hsi s “« xlra" branch mnemonics (common synonyms for the Mo¬ 
torola defined iiiihmiiohh s) appears below. 

Linker Constraints 

It is not possible to make an external reference that will fix up a byte. For example: 

.extern frog 

move.l frog(pc,d0),dl 
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Branch Synonyms 


Alternate name 

Becomes: 

blis 

bee 

bio 

bes 

bzo, bz 

bo<| 

buy. 

bne 

dblo 

clbes 

<lb/,<! 

dbcq 

(lbra 

(lbf 

(ll)hs 

(lbhi 

(11)117, 

dime 


is illegal (anil generates an assembly error) when frog is external, because the 
displacement occupies a byte field in the <>8000 offset word, which the object file 
cannot represent. 

C>X>tiniizations and Translations 

The assembler provides ’'creature comforts" when it processes (>8000 mnemonics: 

o CLR.x An will really generate' SUB.x A/j.A/i. 

o ADD, SUB and CMP with an address register will really generate ADDA, 
SUBA and CMPA. 

o The ADD, AND, CMP, EOR, OR and SUB mnemonics with immediate 
first operands will generate the "I" forms of their inst ruct ions (ADDI, etc.) if 
tin' second operand is not register direct. 

o All shift inst ruct ions with no count value' assume a count of one. 

o MOVE.L is optimized to MOVEQ if the immediate operand is defined and 
in the range —128 . .. 127. However, ADD and SUB are never translated to 
their ipiick forms: ADDQ and SUBQ must be explicit. 
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Macros 


A macro definition is a series of statements of the form: 

.macro name [ forma l-arg 9 ...] 

statements making up the macro body 

. endm 

The name of the macro may he any valid symbol that is not also a 68000 instruction 
or an assembler directive. (The name may begin with a period — macros cannot 
be made confined the way labels or equated symbols can be). The formal argument 
list is optional; it is specified with a comma-seperated list of valid symbol names. 
Note that there is no comma between the name of the macro and the name of the 
first formal argument 

A macro body begins on the line after the .macro directive. All instructions 
and directives, except other macro definitions, are legal inside the body. 

The macro ends with the .endm statement. If a label appears on the line with 
this directive, the label is ignored and a warning is generated. 


Parameter Substitution 

Within t he body, formal parameters may be expanded with the special forms: 

\name 

\{name> 

The second form (enclosed in braces) can be used in situations when' the characters 
following the formal parameter name are valid symbol continuation characters. This 
is usually used to force concatentation, as in: 

\{frog}star 

\{godzilla}vs\{reagan} 


The formal parameter name is terminated with a character that is not valid in 
a symbol (e.g. whitespace or puncuation); optionally, the name may be enclosed in 
curly-braces. The names must be symbols appearing oil the formal argument list, 
or a single decimal digit (\1 corresponds to the first argument, \2 to the second, 
\9 to the ninth, and \0 to the tenth). It is possible for a macro to have more than 
ten formal arguments, but arguments 11 and on must be referenced by name, not 
by number. 

Other special forms are: 


24 MADMAC Reference Manual 



Macros 


Special Form 

Description 

w 

\* 

\# 

\! 

\?name 

\?{name> 

a single "\" 

a unique label of the form "M n" 

the number of arguments actually specified 

the "dot-size" specified on the macro invocation 

conditional expansion 

conditional expansion 


The last two forms are identical: if the argument is specified and is non-empty, the 
form expands to a "1", otherwise (if the argument is missing or empty) the form 
expands to a "0". 

The form "\!" expands to the "dot-size" that was specified when the macro 
was invoked. This can he used to write macros that behave differently depending 
on the size suffix they are given, as in this macro which provides a synonym for the 
"<lc" directive: 


.macro deposit value 
dc\! \value 
. endm 

deposit.b 1 ; 

deposit.w 2 ; 

deposit.l 3 ; 

deposit 4 ; 


byte of 1 
word of 2 
longword of 3 

word of 4 (no explicit size) 


Macro Invocation 

A previously-defined macro is called when its name appears in the operation field of 
a statement. Arguments may be specified following the macro name; each argument 
is scperated by a comma. Arguments may be empty. Arguments are stored for 
substitution in the macro body in the following manner; 

o Numbers are converted to hexadecimal. 

o All spaces outside strings are removed. 

o Keywords (such as register names, dot sizes and ' operators) are converted 
to lowercase. 

o Strings arc enclosed in double-quote marks ( M ). 

For example, a hypothetical call to t he macro "mymacro", of the form; 

mymacro AO, , 'Zorch' / 32, * "DEFINED foo, , , tick tock 
will result in the translations; 


Argument 

Expansion 

( ommciit 

m 

aO 

"AO" converted to lower-case 

\2 


empty 

\3 

,, Zorch ,, /$20 

"Zorch" in double-quotes. 32 in hexadecimal 

\4 

""defined foo 

‘ DEFINED" converted to lower-case 

\5 


empty 

\6 


empty 

\7 

ticktock 

spaces removed (note concatenation) 


The .cxitm directive will cause an immediate exit from a macro body. Thus 
the macro definition: 
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.macro foo source 

.iif !\?source, .exitm ; exit if source is empty 
move \source,dO ; otherwise, deposit source 

. endm 


will not generate the move instruction it the argument "source" is missing from 
tin. 4 macro invocation. 

The .end, .endil* and .exitm directives all pop-out of their include levels 
appropriately. That is, if a macro performs a .include to include a source file, an 
executed .exitin directive within the include-lile will pop out of both the include-file 
and the macro. 

Macros may he recursive or mutually recursive to any level, subject only to 
the availability of memory. When writing recursive macros, take care in the coding 
of the termination condition(s). A macro that repeatedly calls itself will cause the 
assembler to exhaust its memory and abort the assembly. 


Example Macros 


The Gerndos macro is used to make 4 file system calls. It lias two parameters, a 
function number and the number of bytes to clean off the stack after the call. The 
macro pushes the function number onto the stack and does the trap to the file 
system. After the trap returns, conditional assembly is used to choose an addq or 
an add.w to remove the arguments that were pushed. 


macro Gemdos trpno, clean 
move.w #\trpno,-(sp) 

trap #1 

.if \clean <= 8 
addq #\clean,sp 

. else 

add.w #\clean,sp 

.endif 
endm 


; push trap number 
; do GEMDOS trap 

; clean-up up to 8 bytes 

; clean-up more them 8 bytes 


The Foptiii macro is supplied two arguments; the address of a filename, and 
the open mode. Note that plain move* instructions are used, and that the caller of 
the macro must supply an appropriate addressing mode (e.g. immediate) for each 
argument. 

.macro Fopen file, mode 
move.w \mode,-(sp) 

move.l \file,-(sp) 

Gemdos $3d,8 

.endm 

The String macro is used to allocate storage for a string, and to place the 
string's address somewhere. The first argument should be a string or other expres¬ 
sion acceptable in a dc.l) directive. The second argument is optional; it specifies 
where the address of the string should he placed. If the second argument is omitted, 
the string's address is pushed onto the stack. The string data itself is kept in the 
data segment. 


; push open mode 
; push address of file name 
; do the GEMDOS call 
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Macros 


.macro String str,loc 
.if \?loc 
move.l #.\~,\loc 
. else 
pea .\~ 

.endif 
.data 

A": dc.b \str,0 
.text 
. endm 


if loc is defined 

put the string's address there 
otherwise 

push the string's address 

put the string data 
in the data segment 
and switch back to the text segment 


The construction will expand to a label of the form “.Mu” (where it is 

a unique number for every macro invocation), which is used to tag the location of 
the string. The label should he confined because the macro may be used along with 
other confined symbols. 

Unique symbol generation plays an important part in the art of writing line 
macros. For instance, if we needed three unique symbols, we might write ".aV", 
“.b\~" and “.cVA 


Repeat Blocks 

Repeat-blocks provide a simple iteration capability. A repeat block allows a range 
of statements to be repeated a specified number of times. For instance, to generate 
a table consisting of tin' numbers 255 through 0 (counting backwards) you could 
write: 


.count set 255 

.rept 256 
dc.b .count 

.count set .count - 1 

.endr 


initialize counter 
repeat 256 times: 
deposit counter 
and decrement it 
(end of repeat block) 


Repeat blocks can also be used to duplicate identical pieces of code (which are 
common in bitmap-graphics routines). For example: 


.rept 16 
clr.w (a0) + 
. endr 


clear 16 words 
starting at AO 
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6502 Support 


M AI)M A( 1 will general** code for the Motorola (>502 microprocessor. This chapter 
describes extra addressing mod<*s and directives used to support the 6502. 

As the (5502 object code is not linkable (currently t here is no linker) external 
references may not be made. (Nevertheless, M A DM AC may reasonably be used for 
large assemblies because of its blinding speed.) 

All standard 6502 addr<*ssing mode's are supported, with the exception of the 
accumulator addressing form, which must be omitted (e.g. 'Tor a" becomes Tor"). 
Five* extra mode's, synonyms for existing ones, are* included for compatibility with 
t he Atari Coinop assembler. 

empty implied or accumulator (e.g. tsx or ror) 

expr absolute or zeropage 

#expr immediate 

( expr , x) indirect X 

(expr) ,y indirect V 

(expr) indirect 

expr,x indexed X 

expr, y indexed V 

Qexpr(x) indirect X 

Oexpr (y) indi reel V 

Qexpr indirect 

x, cxpr indexed X 

y, expr indexed Y 

While M A DM AC lacks “high" and “low" operators, high bytes of words may 
be extracted with the shift (») or divide (/) operators, and low bytes may be 
extracted with the bitwise AND (&) operator. 

.6502 

This directive enters the (>502 section. The location counter is undefined, and 
must be set with ".org" before any code can be generated. 

The “de.w" directive will produce 6502-format words (low byte first). The 
68000's reserved keywords (d0-d7/a0-a7/ssp/usp and so on) remain reserved 
(and thus unusable) while in the 6502 section. The directives globl, dc.l, 
dcb.l, text, data, bss, abs, even and comm are illegal in tin* (5502 section. 
It is permitted, though probably not useful, to generate both 6502 and (>8000 
code in the same object file. 

.68000 

This directive leaves the (5502 segment and returns to the (58000's text segment. 
68000 instructions may be assembled as normal. 

.org location 

This directive is only legal in the (5502 section. It sets the value of the location 
counter (or pc) to location, an expression that must lx* defined, absolute, and 
less than $10000. 
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0502 Support 


WARNING 

It is possible to assemble “beyond'' the microprocessor s (S I K address space, but 
attempting to do so will probably screw up the assembler. DO NOT attempt 
to generate code like this: 

.org $fffe 

nop 

nop 

nop 

the third NOR in this example, at location $10000. may cause the assembler 
to crash or exhibit spectacular schizophrenia. In any case, M A DM AO will give 
no warning before linking out. 

Object Code Format 

This is a little bit of a kludge. An object lile consists of a page map. followed by 
one or more page images, followed by a normal Alcyon (58000 object tile. If the page 
map is ail zero, it is not written. 

The page map contains a byte for each of the 25(5 250-byte pages ill the (5502 s 
(54K address space. The byte is zero ($00) if the page contained only zero bytes, or 
one ($01) if the page contained any non-zero bytes. If a page is (lagged with a one, 
then it is written (in order) following the page map. 

The following code: 

.6502 

.org $8000 
.dc.b 1 
.org $8100 
.dc.b 1 
.org $8300 
.dc.b 1 
.end 

will generate a page map that looks (to a programmer) something like: 

<$80 bytes of zero> 

01 01 00 01 

<$7c more bytes of zero, for $100 total> 

<image of page $80> 

<image of page $81> 

<image of page $83> 

following the last page image is an A Icy on-format object file', starling with 
the magic number $601a. It may contain (5N000 code (although that is probably 
useless), but the symbol table is valid and available for debugging purposes. (5502 
symbols will In* absolute (not in text, data or bss). 
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Error Messages 


When Things Go Wrong 

Most of M A DM A( °s error messages are self-explanatory. They fall into four classes: 
warnings about situations that you (or the assembler) may not be happy about, 
errors that cause the assembler to not generate object files, fatal errors that cause 
the assembler to abort immediately, and internal errors that should never happen. 1 

You can write editor macros (or sed or awk scripts) to parse the error messages 
M A DM A( 1 generates. When a message is printed, it is of the form: 

" filenaine" , line linc-mnnher: message 

The first element, a filename enclosed in double quotes, indicates the file that gen¬ 
erated the error. The filename is followed by a comma, the word "line", and a line 
number, and finally a colon and the text of the message. The filename "(*top*)" 
indicates that the assembler could not determine which file had the problem. 

The following sections list warnings, errors and fatal errors in alphabetical 
order, along with a short description of what may have caused the problem. 

Warnings 

bad backslash cock* in string 

You tried to follow a backshish in a string with a character that the assembler 
didn't recognize. Remember t hat M A DM AC uses a ( ’-style escape system in 
strings. 

label ignored 

You specified a label before a macro, rept or ondni directive. The assembler 
is warning you that the label will not be defined in the assembly. 

unoptiinized short branch 

This warning is only generated if the -s switch is specified on the command 
line. The message refers to a forward, unsized long branch that you could have 
made short (.s). 

Fatal Errors 
cannot continue 

As a result of previous errors, the assembler cannot continue processing. The 
assembly is aborted. 

line too long as a result of macro expansion 

When a source line within a macro was expanded, the resultant line* was too 
long for M A DM AC (longer than 200 characters'or so). 


1 If you come* across ail in Vernal error, we would appreciate' it if you would contact 
Atari Technical Support and let us know about the problem. 
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Vrror Messages 


memory exhausted 

l he assembler ran out of memory. You should (1) split up your source files 
and assemble them seperately, or (2) if you have any ramdisksor RAM-resident, 
programs (like desk ace-e'sseirie's) decrease' their size so that the' assembler has 
11 Hire RAM to work with. As a rule' ol thumb, pure 08000 rode will use 1 up to 
t wice the number of bytes contained in the source files, whereas 0502 code will 
use <>4K of ram right away, plus t he size' of the' source file's. The assembler itself 
use's about 80K byte's. Cot out your calculator... 

too many ENDMs 

The assembler ran across an endm directive when it wasn't expecting to see 
one', l he' assembly is aborted, ( lu ck the nesting of your macro ele'finitions 
you probably have an extra endm. 

Errors 

•cargs syntax 

Syntax error in .cargs elirective. 

•comm symbol already defined 

You tried to .comm a symbol that was alreaely defined. 

.ds permitted only in BSS 

You t ried to use .ds in the text or data section. 

•init not permitted in BSS or ABS 

You trie'el te> use' .init in the BSS or ABS section. 

.org permitted only in .6502 section 

You trie'el to use' .org in a (>8000 section. 

Cannot create: (ih'iiame 

T\\e assembler could not create the indicated filename. 

External quick reference 

You trie'el to make' the' iiimtexliate' operand of a moveq, suhq or add<j instruc¬ 
tion external. 

PC-relative* expr across sections 

You true! te> make' a P< -relative refere'iice to a location contained in another 
sect le >ll 

[bwsl] must follow \* in symbol 

You i rt< d i< follow a dot in a symbol name' with some.'!.hing other than one.' of 
the four ( li^r.u i*t> *B . *YY , *S or *L . 

addressing tuod<* syntax 

You mad* « ^vntax rrror in an addressing mode. 

assert failure 

Oik' of y.iif .assert elire'ctives failed! 

bael (section) expression 

You tried lu mix ami match sections in an expression. 

bad 6502 addressing mode 

The (>502 mnemonic will not work with the addressing mode you specified, 
bad expression 

There's a syntax error in I lie' expression you lypeel. 
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Error Messages 


bad size specified 

You tried to use an inappropriate size suliix for the instruction, (’heck your 
(>8000 manual for allowable sizes. 

bad size suffix 

You can't use .b (byte) inode with the movem instruction. 

cannot .globl local symbol 

You tried to make a confined symbol global or common. 

cannot initialize non-storage (DSS) section 

You tried to generate instructions (or data, with dc) in tin' BSS or ABS section. 

cannot use \b* with an address register 

You tried to use a byte-size suffix with an address register. The (>8000 does not 
perform byte-sized address register operations. 

directive illegal in .6502 section 

You tried to use a 68000-oriciitcd directive in tin' (5502 section. 

divide by zero 

The expression you typed involves a division by zero, 
expression out of range 

The expression you typed is out of range for its application, 
external byte reference 

You tried to make a byte-sized reference to an external symbol, which the 
object file format will not allow. 

external short branch 

You tried to make a short branch to an external symbol, which the linker cannot 
handle. 

extra (unexpected) text found after addressing mode 

MADMAC thought it was done processing a line, but it ran up against “extra" 
stuff Be sure that any comment on the line begins with a semicolon, and check 
for dangling commas, etc. 

fox*ward or undefined .assert 

The expression you typed after a .assert directive had an undefined value. 
Remember that MAI)MA<* is one-pass. 

hit EOF without finding matching .ondif 

fhe assembler fell off the end of last input file without finding a .endif to 
match an .if. You probably forgot a .endif somewhere. 

illegal 6502 addressing mode 

The 6502 instruction you typed doesn't work with the addressing mode you 
specified. 

illegal absolute expression 

You can't use an absolute-valued expression here. 

illegal bi-a.s with zero offset 

You can't do a short branch to the very next instruction (read your (580 00 
manual). 

illegal byte-sized relative reference 

The object file format does not permit bytes contain relocatable values; you 
tried to use a byte-sized relocatable expression in an immediate addressing 
mo<l<'. 
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Em >r A /essages 


illegal character 

Your source file contains a character that MADMAC doesn't allow, (most 
control characters fall into this category). 

illegal initialization of section 

You tried to use .do or .dch in the BSS or ABS sections. 

illegal r<dative address 

File relative address you specified is illegal because it belongs to a different 
section. 

illegal word relocatable (in .PRG mode) 

You can't have anything other than long relocatable values when you're gener¬ 
ating a .PRG file. 

inappropriate addressing mode 

The mnemonic you typed doesn't work with the addressing modes you specified, 
(’■heck your (>8000 manual for allowable combinations. 

invalid addressing mode 

The combination of addressing modes you picked for the movein instruct ion 
are not implemented by the G8000. Check your 08000 reference manual for 
details. 

invalid symbol following ~~ 

What followed the ~~ wasn't a valid symbol at all. 

mis-nosted .endr 

The assembler found a .endr directive when it wasn't prepared to find one. 
Check your repeat-block nesting. 

mismatched .else 

The assembler found a .else directive when it wasn't prepared to find one. 
Check your conditional assembly nesting. 

mismatched .endif 

The assembler found a .endif direct ive when it wasn't prepared to find one. 
(■heck your conditional assembly nesting. 

missing “=* 
missing *>* 

missing argument name 
missing close parenthesis *)* 
missing close parenthesis *] * 
missing comma 
missing filename 
missing string 
missing symbol 

missing symbol or string 

The assembler expected to see a symbol/filename/string (etc...), but found 
somet hing else instead. In most cases the problem should he obvious. 

misuse of \\ not allowed in symbols 

You tried to use a dot (.) in the middle of a symbol name. 

mod (%) by zero 

The expression you typed involves a modulo by zero. 
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Error Messages 


multiple formal argument definition 

The list of formal paramet er names you supplied for a macro definit ion includes 
two identical mimes. 

multiple macro definition 

You t ried to define a macro which already had a definition, 
non-absolute byte reference 

You tried to make a byte reference to a relocatable value, which the object file 
format, does not allow. 

non-absolute byte value 

You tried to dc.b or deb.b a relocatable value. Byte relocatable values are 
not permitted by the object file format . 

register list order 

You tried to specily a register list like D7-D0, which is illegal. Kememher 
that the lirst register number must be less t han or equal to the second register 
number. 

register list syntax 

You made an error in specifying a register list for a .reg directive or a .movcm 
instruction. 

symbol list syntax 

You probably forgot a comma between the names of two symbols in a symbol 
list, or you left a comma dangling on the end of the line. 

syntax error 

This is a "catch-air error. 

undefined expression 

The expression has an undefined value because of a forward reference, or an 
undefined or external symbol. 

unimplemented addressing mode 

You tried to use (>8020 "square-bracket" notation for a (>8020 addressing mode. 
MADMAC * does not support 158020 addressing modes. 

uuimplemeu t< •« I diree ti ve 

You have found a directive that didn't appear in the documentation. It doesn't 
work. 

miimplement«•< I mix*nn>nio 

You've found tin avNi'inhler (or documentation) bug. 

unknown symbol following 

Y ou follow.I .t with somet hing other t han one of the names defined, ref¬ 
erenced or streq 

unsupported G8020 addressing mode 

The assembler .» US020-type addressing mode. MADMAC docs not assem¬ 
ble code for lit* r»M)20 or 080 10. 

uiiterminated string 

You specified a Mrni” starting with a single or double quote, but forgot to type' 
the closing quote. 

write error 

The assembler had a problem writ ing an object lile. 'This is usually caused by 
a full disk, or a bad sector on the media. 
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